home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / batchut / ask3.zip / ASK3.DOC < prev    next >
Text File  |  1986-12-11  |  14KB  |  388 lines
  1.  
  2. 1. QUICK START
  3.  
  4. ASK allows you to ask for input from the user in a batch file. The 
  5. simplified syntax is 
  6.  
  7.   ASK [prompt] [expected Keys]
  8.  
  9. Prompt is a "quoted" string that will be printed by ASK. Expected 
  10. keys is a list of key that you expect from the user. The result 
  11. is testable by the "if errorlevel" statement in a batch file. For 
  12. example (in a batch file): 
  13.  
  14.   echo off
  15.   ask "Do you want to run away (y/n)? " yn
  16.   if errorlevel 2 goto no
  17.   rem *** errorlevel 1 falls thru here. Now run away.
  18.   away
  19.   :no
  20.  
  21. When the user runs this batch file, he will get this prompt:
  22.  
  23.   Do you want to run away (y/n)? _
  24.  
  25. He can press the 'y' or the 'n' key. If he presses the 'y'
  26. key, errorlevel will be set to 1 (because y is the first
  27. character in the expected keys list) and away will be run.
  28. If he presses the 'n' key, errorlevel will be set to 2 and
  29. away will not be run.
  30.  
  31. This should get you started. There are some other examples
  32. in this document as well as in the file EXAMPLE.BAT (which
  33. you can run).
  34.  
  35. 2. REFERENCE
  36.  
  37. 2.1 Introduction
  38.  
  39. ASK is a program for you to use in a batch file to ask for one-
  40. key responses from the user. ASK then sets the errorlevel 
  41. according to the key pressed. The errorlevel can be tested in a 
  42. batch file to branch to different places. This allows you to ask 
  43. simple questions like the Yes-or-No type, or to set up a menu-
  44. driven batch file. ASK also accepts options like no echo, time 
  45. out, flush type-ahead. 
  46.  
  47.  
  48. 2.2 Syntax
  49.  
  50. ASK [Options] [Prompt] [Expected Keys]
  51.  
  52.  
  53. 2.2.1 Prompt
  54.  
  55. [Prompt] is the question to be displayed. It is a "quoted string" 
  56. (double quotes only). You can embbed double quotes in the prompt 
  57. by using \" (backslash-quote). If you do not supply [Prompt], ASK 
  58. will use the default '? '. If you want an empty prompt, use "".
  59.  
  60.  
  61. 2.2.2 [Expected Keys]
  62.  
  63. [Expected Keys] is a string of all the different keys that the 
  64. user may press in response to your question. There is no need to 
  65. quote this string unless you want to include a space in it. 
  66. Another way to include a space is to use '\ ' (blackslash-space). 
  67.  
  68. If the user presses the first key listed in the [Expected Keys], 
  69. the errorlevel will be set to 1; if the user presses the second 
  70. key in the [Expected Keys], the errorlevel will be set to 2, and 
  71. so on. If the user presses a key that is not in the [Expected 
  72. Keys], ASK will beep and prompt him again until he gets it right. 
  73. You can override this action with the /q option. 
  74.  
  75. If the [Expected Keys] string is not present, the errorlevel will 
  76. be set to the character code of the key the user pressed. By 
  77. default, lower case letters will be mapped to the upper case 
  78. counterpart, i.e. letters always return 65-90. You can disable 
  79. this mapping with the /c option. 
  80.  
  81. If there is no [Expected Keys] and the user presses a key that 
  82. maps to an extended ASCII, ASK returns 0 (zero). The only way to 
  83. match a function key is to list that key in [Expected Keys]. 
  84.  
  85. When testing errorlevel, be sure to test for the highest number 
  86. first because 
  87.  
  88.     if errorlevel 5
  89.  
  90. means
  91.  
  92.     if errorlevel equal to or greater than 5.
  93.  
  94.  
  95. 2.3 Options
  96.  
  97. Options are used to change the behavior of ASK somewhat. The 
  98. option letters themselves are not case sensitive so you can use 
  99. either upper or lower case. 
  100.  
  101.      /F    - flush all keys type-ahead before accepting input
  102.  
  103.      /E    - no echo. Accept input but do not echo it to the 
  104.              screen. The cursor is also turned off during input. 
  105.  
  106.      /Q    - be quiet, don't yell at the user for invalid              
  107.              response, but return 0 as the errorlevel. This 
  108.              option is meaningless if there is no [Expected 
  109.              Keys]. This is normally used when you want to trap 
  110.              invalid responses and print your own error message 
  111.              instead of using the built-in one. 
  112.  
  113.      /C    - make [Expected Keys] case sensitive. This means 
  114.              letters pressed by the user will only match letters 
  115.              in the same case in [Expected Keys]. If there is 
  116.              no [Expected Keys], then UPPER case letters will 
  117.              return errorlevel 65-90, and lower case letters will 
  118.              return 97-122. 
  119.  
  120.      /Sxxx - timeout after xxx seconds and return errorlevel 255. 
  121.              xxx can be from 1 to 3 digits and range from 0 to 
  122.              999.
  123.  
  124.              If you supply 0 (zero) as the timeout value, ASK 
  125.              will check the keyboard buffer once before it times 
  126.              out. If there is a key in the buffer (typed ahead), 
  127.              ASK will read it. 
  128.  
  129.              If you do not supply any value, ASK will time out 
  130.              immediately without even checking type-ahead keys in 
  131.              the keyboard buffer. You can use ASK this way as an 
  132.              alternative to DOS' ECHO command. The advantage is 
  133.              that you can use ASK to print control characters. E.g. 
  134.              ask/s "\e" > E.TXT will put the escape character in 
  135.              the file E.TXT. 
  136.   
  137.              If more than one timeout option is given, the effect 
  138.              is cumulative. Accuracy is from +0 to -1 second. So 
  139.              if you say s10 it would delay from 9 to 10 seconds. 
  140.  
  141.              When ASK times out it will not print a linefeed so 
  142.              that the next thing you ECHO will appear immediately 
  143.              after the [prompt]. I usually print *TIMEOUT* so if 
  144.              a user is watching he will understand why things are 
  145.              happening even though he didn't press any key. 
  146.  
  147.      /Myyy - timeout after yyy minutes and return errorlevel 255. 
  148.              yyy can be from 1 to 3 digits and range from 0 to 
  149.              999. See the /S option for other details.
  150.  
  151. More than one option letter can share a common switch, like
  152. this:
  153.  
  154.         ask /QS50C "Blah Blah? "
  155.         ask/qcm5  "Blah Blah? "
  156.         ask /c/s9/q "Blah Blah ?"
  157.  
  158.  
  159. 2.4 Special Characters
  160.  
  161. Characters that you normally cannot put on a command line (e.g. 
  162. carriage return, escape, backspace, ...) can be included in 
  163. either [Prompt] or [Expected Keys] using the following 
  164. conventions: 
  165.  
  166.      \nnn - translates to ASCII nnn where nnn is a 3-digit 
  167.             decimal number. If this is not followed by another 
  168.             digit then you don't need to put down all three 
  169.             digits. If it is followed by a digit, then you have 
  170.             to put down all three digits (add leading zeros if 
  171.             necessary). 
  172.  
  173.                For example:
  174.  
  175.                  ASK "\7HI: "       prints a beep and "HI: "
  176.                  ASK "\0070 HI: "   prints a beep and "0 HI:"
  177.                  ASK "\070 HI: "    prints "F HI: "
  178.  
  179.      \e  -  the escape character. This is equivalent to \27, 
  180.             \027, or \E. 
  181.  
  182.      \\  -  the \ (backslash) character itself
  183.  
  184.      \"  -  the double quote character (without the backslash it 
  185.             will be interpreted as the beginning or the end of a 
  186.             quoted string). 
  187.  
  188.      \~  -  the tilde character itself.
  189.  
  190.      ~a  -  translates to control-a. This works when 'a' is from 
  191.             ASCII 64 to 95 (which produce ASCII 0 thru 31) or is 
  192.             a lower case letter. 
  193.  
  194.      ~(X) - interpret this as a function key. X is the label on 
  195.             the function key. E.g. ~(f1) refers to the key (F1), 
  196.             ~(ins) refers to the (Ins) key.
  197.    
  198.             The label is not case sensitive, so you can use upper 
  199.             or lower case. So ~(F1), ~(INS) would also work.
  200.  
  201.             You can use the prefixes S-, C-, and A- with the 
  202.             labels to denote Shift-, Ctrl-, and Alt- version of 
  203.             the key, like ~(s-f1), ~(c-f1), and ~(a-f1). 
  204.  
  205.             This notation is only recognized in [Expected Keys] 
  206.             and not in [Prompt], because function keys cannot be 
  207.             printed. 
  208.  
  209. Here's some examples on using special characters:
  210.  
  211.      ask "How \"are\" you?"  - will produce  How "are" you?
  212.      ask "Hi?\7"             - will produce  Hi?*BEEP*
  213.      ask "Hi?~g"             - will also